StarIO for Windows®

StarIO is a high level programming tool that simplifies the development and creation of software for Star printers.  StarIO exposes an easy-to-use API that gives you fundamental communications access to the printer.  This API is supplied pre-formed for all the most popular programming environments including Java and .NET, and exposes the same functionality regardless of the printer model or the communications interface you’re using.

Getting Started

The following explains how to setup your StarIO based development project:

Visual C++

To use StarIO in your Visual C++ project: include the StarIOPort.h header file, link against the StarIOPort.lib library file, and finally run with StarIOPort.dll in the application directory.  C / C++ documentation is written in-line with the function declarations in StarIOPort.h.

Visual C# and Visual Basic .NET

To use StarIO in your .NET project: reference the StarIO.dll .NET assembly and run with both StarIO.dll and StarIOPort.dll in the application directory.  C# and VB.NET documentation is available in the StarIO.xml file. Keep this XML file in the same directory as StarIO.dll and view the documentation using Visual Studio’s IntelliSense and Object Browser features.

Java

To use StarIO in your Java project: simply add StarIO.jar to both the compile (javac) and the runtime (java) classpath definitions and then run with StarIO.jar, StarIOJ.dll, and StarIOPort.dll in the application directory.  Java documentation is available in JavaDOC HTML format in the documentation directory.

VB 6

To use StarIO in your VB 6 project: simply add the StarIOPort.bas file as a module and run with StarIOPort.dll in the application directory.  VB 6.0 documentation is written in-line with the function declarations in StarIOPort.bas.

Programming & Usage

Your usage of StarIO always begins by opening a port; in C programs this is done via the OpenPort function, in .NET programs this is done by calling the Port class’s static GetPort method, in Java programs this is done by calling the StarIOPort class’s static getPort method.

All of these functions will, when successful, return a port handle (or object) back to you.

When the port that you’ve requested could not be opened these functions will fail; the C API’s OpenPort function will simply return 0 (zero) to indicate failure, in the .NET scenario a PortException will be thrown, and in the Java scenario a StarIOPortException will be thrown.

OpenPort will fail if the specified port does not exist, or if the specified port settings cannot be applied to the port, or if any of the underlying OS system calls fail themselves; these such failures generally indicate a serious failure that you’ll want to investigate.  OpenPort also fails when another process has already opened the port that you’re attempting to use.  This is a failure that you can likely recover from.

In C programs you can distinguish between these two kinds of failures by calling the GetLastError API - if the result is ERROR_ALREADY_EXISTS then you know that another process currently has the port opened and that you should call the OpenPort API again after waiting for a short while.

In C# and Java programs you can check the IsPortInUseFailure property of the exception - if that property is set to true then you’ll want to retry the OpenPort call.

Once you have successfully opened the port you can use all the other StarIO APIs.  In C programs all other APIs take the port handle as the first parameter.  In .NET and Java you simply call the port object’s methods.

When you have finished using the port you must close it.  In C programs this is done by calling the ClosePort API.  In .NET programs this is done by calling the Port.ReleasePort static method.  In Java programs this is done by calling the StarIOPort.releasePort static method.  When writing programs in one of the .NET languages or in Java, it is often convenient to close the port in the finally part of a try / catch / finally construct.

In general, it is easier to coordinate the various parts of your system if you close ports as soon as you’re done using them, rather than holding them open indefinitely.

The other APIs function as described in the API documentation.

Port Names & Settings

The OpenPort function accepts three parameters: the port name, the port settings, and the communication timeout.  We’re explaining the port naming and settings parameters here because these are very important:

USB - Printer Class Mode

  • The port name parameter is formed by combining “USBPRN:” with your printer’s Windows® printer queue name.  For example, when you connect a Star TSP700II USB printer the “Star TSP700II (TSP743II)” printer queue gets created for it.  To access this printer via StarIO you would call the OpenPort function with “USBPRN:Star TSP700II (TSP743II)”.
  • The port settings parameter must be the empty string: “”.

USB - Vendor Class Mode

  • Three different port name parameter forms are accepted:
    • “usbven:” instructs StarIO to open the first Star USB Vendor Class device it finds.  This is useful when your printer doesn’t have a USB serial number set (which is the default state).  When there is no USB serial number set, connecting your printer to different USB ports on the computer will cause it to be assigned varying COM port names - and this would otherwise complicate the use of OpenPort.  The “usbven:” port Name format eliminates this as a concern by opening the first device it finds regardless of the COM port name it has been assigned.  When your deployment circumstance involves only a single printer and that printer hasn’t been configured with a USB serial number, this is probably your best choice.
    • “usbven:snsnsnsn” causes StarIO to open the printer whose serial number you’ve specified.  This is useful in two scenarios: 1) to avoid new ports being created when the printer is connected to the computer's different USB ports and hibs, and 2) when you have multiple printers connected simultaneously.  Note: Star’s printers do not have USB serial numbers configured from the factory - you’ll have to write a serial number into the device in order to use this facility.
    • “usbven:COM4” or “usbven:COMx” causes StarIO to open communications with the printer based on the COM port name it’s been natively assigned.  You can determine what name this is by looking in the Windows® Device Manager.  Note: while this facility is useful in some contexts, it may cause difficulties if the printer is variously connected to different USB ports on the computer; each time it gets connected to a different USB port it will be assigned a new COM port name (unless it has been assigned a serial number - see above).
  • The port settings parameter must be an empty string: “”.

Ethernet

  • The port name parameter is formed by combining “TCP:” with your printer’s IP address.  For example, if your printer is established on the 192.168.1.102 address then you would pass “TCP:192.168.1.102” in as the port name parameter.
  • The port settings parameter must be the empty string: “”.

Parallel

  • The port name parameter is simply the parallel port name like “LPT1” or “LPT2” etc.
  • The port settings parameter must be the empty string: “”.

Serial

  • The port name parameter is simply the serial port name like “COM1” or “COM2” etc.
  • The port settings parameter is a comma-separated string containing the following fields.  When these fields are assembled into a single string it will take on this form: “baudRate,parity,dataBits,stopBits,flowControl” as in “9600,n,8,1,n”.
    • The baudRate field can be one of: “38400”, “19200”, “9600”, “4800”, or “2400”.
    • The parity field can be one of “n” for none, “e” for even, or “o” for odd.
    • The dataBits field can be one of “7” or “8”.
    • The stopBits field must be “1”.
    • The flowControl field can be “n” for no flow control or “h” for hardware flow control.

Programming Samples

The following sample projects are included:

Version Status

The following statements describe this release and any currently known problems.  You are encouraged to read and understand these so that your own deployment of this solution can be made successful.  We are currently working to resolve these problems; check back for updated versions of this document and of this software.

 

Version History

Legal Information

Copyright 2008 Star Micronics Co., Ltd. All rights reserved.  All trademarks acknowledged.  Windows® is a registered trademark of the Microsoft Corporation.